.. _Using NeurEcoDNN:

Tutorial: using NeurEco command line interface for a Tabular Regression problem
====================================================================================

**NeurEcoDNN** is the executable used for building, evaluating and exporting **Tabular** models (**Regression**, **Classification**, **Compression**). The executable can be called directly from a terminal / powershell only after a full installation.

.. note:: 
	When using a portable version of the software, make sure to add its *bin* directory to the environment variable PATH.

To call the executable, simply run the following command:

.. code-block:: shell

	neurecoDNN

which will output:

.. code-block:: text

	     _   __                ______
	    / | / /__  __  _______/ ____/________
	   /  |/ / _ \/ / / / ___/ __/ / ___/ __ \
	  / /|  /  __/ /_/ / /  / /___/ /__/ /_/ /
	 /_/ |_/\___/\__,_/_/  /_____/\___/\____/
	                 === A D A G O S ===

	Version: 4.01.2591.0 Compiled with MSVC v1928  Dec  5 2022 Matlab runtime:no
	OpenMP: yes
	MKL: yes
	Version Ref: 27284d298a51ac68c0443ce3e5caee63cd26acb0
	usage: neurecoDNN [-h] [command <parameters>]

	Entry point for NeurEco model building and evaluation.

	Commands:
	build <configurationFilename>
	          build a neureco model from a given input solution/input set.
	evaluate <configurationFilename>
	          evaluate a deepROM model from a given excitation.
	exportC <NeurecoFilename path> <CFilename path> <precision>
	exports NeurecoFilename model as an .h file

	exportFMU <NeurecoFilename path> <fmuFilename path> <platform identifier>
	    export NeurecoFilename model as an FMU file
	  platform: 1=windows, 2=linux, 3=both, default: both.

	exportONNX <NeurecoFilename path> <ONNXFilename path> <precision>
	exports NeurecoFilename model as an ONNX file

	exportVBA <NeurecoFilename path> <VBA Filename path> <precision>
	exports NeurecoFilename model as an .bas file

	...

	Optional arguments:
	-h, --help   show this message and exit

The following section uses the test case :std:ref:`Energy consumption test case`. This test case is delivered with the NeurEco installation package.

To build a **Tabular Regression** model using the executable:

* Create a configuration file *.conf* for build, here called *build_configuration_file.conf* (see :std:ref:`Evaluate NeurEco Regression model with the command line interface`).
  For the test case :std:ref:`Energy consumption test case`, the configuration file for build looks as follows:

.. code-block:: javascript

  {
    "neurecoDNN_build": {
      "DevSettings": {
      	"disconnect_inputs_if_possible": true,
      	"final_learning": true,
      	"initial_beta_reg": 0.1,
      	"parameter_number_limit": 0,
      	"valid_percentage": 33.33
      },
      "UserSettings": {
      	"gpu_id": 0,
      	"use_gpu": false
      },
      "build_compress": false,
      "checkpoint_address": "./EnergyConsumption/EnergyConsumption.checkpoint",
      "classification": false,
      "exc_filenames": [
      	"x_train.csv"
      ],
      "freeze_structure": false,
      "input_normalization": {
      	"normalize_per_feature": true,
      	"scale_type": "max_centered",
      	"shift_type": "min_centered"
      },
      "output_filenames": [
      	"y_train.csv"
      ],
      "output_normalization": {
      	"normalize_per_feature": true,
      	"scale_type": "auto",
      	"shift_type": "auto"
      },
      "resume": false,
      "starting_from_checkpoint_address": "",
      "start_build_from_model_number": -1,
      "test_exc_filenames": [
      	"x_test.csv"
      ],
      "test_output_filenames": [
      	"y_test.csv"
      ],
      "write_model_output_to_directory": "./EnergyConsumption/BuildingResults",
      "write_model_to": "./EnergyConsumption/EnergyConsumption.ednn"
    }
  }

* Place this configuration file in the same directory as the data of the test case (*x_train.csv*, *x_test.csv*, *y_train.csv*, *y_test.csv*), otherwise adjust the relative paths to the data files in the configuration file. 

* To launch the build, run the following command in the terminal (opened in the data directory, otherwise adjust the relative path to the configuration file):

.. code-block:: shell

  neurecoDNN build ./build_configuration_file.conf

* The build starts automatically:

.. code-block:: text

  Log initiated with levels: info warning error

  00h00m00s info >
  00h00m00s info >      _   __                ______
  00h00m00s info >     / | / /__  __  _______/ ____/________
  00h00m00s info >    /  |/ / _ \/ / / / ___/ __/ / ___/ __ \
  00h00m00s info >   / /|  /  __/ /_/ / /  / /___/ /__/ /_/ /
  00h00m00s info >  /_/ |_/\___/\__,_/_/  /_____/\___/\____/
  00h00m00s info >                  === A D A G O S ===
  00h00m00s info >
  00h00m00s info > Version: 4.01.2591.0 Compiled with MSVC v1928  Dec  5 2022 Matlab runtime:no
  00h00m00s info > OpenMP: yes
  00h00m00s info > MKL: yes
  00h00m00s info > Reading Dataset...
  00h00m00s info > Reading data files...

To evaluate a **Tabular Regression** model using the executable:

* Create a configuration *.conf* file for evaluation, here called *eval_configuration_file.conf* (see :std:ref:`Evaluate NeurEco Regression model with the command line interface`).
  For the test case :std:ref:`Energy consumption test case`, the configuration file for evaluation looks, for example, as follows:
	
.. code-block:: javascript

   {
      "NeurEcoEvaluate": {
          "exc_filenames": [
              "x_test.csv"
          ],
          "neureco_filename": "./EnergyConsumption.ednn",
          "optional_output_reference": [
              "y_test.csv"
          ],
          "write_model_output_to_directory": "./EvaluationResults"
      }
  }

* Place this configuration file in the same directory as the data of the test case (*x_train.csv*, *x_test.csv*, *y_train.csv*, *y_test.csv*), otherwise adjust the relative paths to the data files in the configuration file 

* To launch the evaluation, run the following command in the terminal (opened in the data directory, otherwise adjust the relative path to the configuration file):
 
.. code-block:: shell

  neurecoDNN evaluate ./eval_configuration_file.conf

* The model is evaluated on the testing data in *"x_test.csv"*, and the results are saved in a the directory created by NeurEco: *"./EvaluationResults"*.

To export the **Tabular Regression** model using the executable (see :std:ref:`Export NeurEco Regression model with the command line interface`, *embed* license is required): 

* To export the model to a C format (header_file), run:

.. code-block:: shell

  neurecoDNN exportC ./EnergyConsumption.ednn ./EnergyConsumption.h double

* To export the model to the ONNX format, run:

.. code-block:: shell

  neurecoDNN exportONNX ./EnergyConsumption.ednn ./EnergyConsumption.onnx float16

* To export the model to the VBA format, run:

.. code-block:: shell

  neurecoDNN exportVBA ./EnergyConsumption.ednn ./EnergyConsumption.onnx float

* To export the model to the FMU format, run:

.. code-block:: shell

  neurecoDNN exportFMU ./EnergyConsumption.ednn ./EnergyConsumption.fmu